//package declaration
package pxgrid_controllers;

//imports
import pxgrid_entities.*;

/**
 * PXGridController
 * An abstract class to define basic grid controller methods,
 * you should extend it when writing new grid controller classes.
 * Note: PX is used as a prefix for all classes created for the MR Grid 
 * (previously PXGrid) project.
 * 
 * @author Mark Bate
 */
public abstract class PXGridController {
    
    /**
     * Takes a PXSubmission, loaded with PXJobs and submits the jobs to grids.
     * Note: each PXJob must have it's:
     * "grid_controller", "job_name", "input_mtz", "input_pdb", "space_group",
     * "f_label", "sigf_label", "molecular_weight", 
     * "number_of_molecules_in_asymmetric_unit", 
     * "number_of_copies_of_ensemble_to_search_for", "rmsd" and "packing"
     * variables set.
     * 
     * @param submission PXSubmission entity loaded with the jobs to submit
     * @return PXSubmission the same PXSubmission of PXJobs with their "grid_job_id" variable
     * set to the job_id assigned by the grid.
     * @throws java.lang.Exception thrown if any of the variables specified 
     * above aren't validly set
     */
    public abstract PXSubmission submitJobsToGrid(PXSubmission submission) throws Exception;
    
    /**
     * Gets the status of a job from the grid
     * @deprecated replaced by getJobAttributes() method, which should return
     * more detail about the job.
     * 
     * @param job_id the id (assigned by the grid) of the job you wish to get 
     * status for
     * @param grid_name the display_name of the grid to query
     * @return String the status of the job.
     * @throws java.lang.Exception thrown if job_id is not greater zero, or if
     * grid_name is null.
     */
    public abstract String getJobStatus(int job_id, String grid_name) throws Exception;
    
    
    /**
     * Gets the attributes of a job from the grid.
     * This method replaces the getJobStatus() method.
     * 
     * Note: the PXJob must have it's grid_controller and grid_job_id variables
     * set.
     * 
     * @param job PXJob the job to get the attributes for
     * @return PXJob the same PXJob with values set for status, is_suspended,
     * start_time, stop_time and submission_time, where applicable.
     * @throws java.lang.Exception thrown if the PXJobs grid_controller 
     * and grid_job_id are not set.
     */
    public abstract PXJob getJobAttributes(PXJob job) throws Exception;
    
    
    /**
     * Gets the results for the PXJob from the grid.
     * Note: the PXJob must have it's:
     * "grid_controller", "job_name", "input_mtz", "input_pdb" and "space_group"
     * variables set.
     * 
     * @param job a PXJob for which to grab the results back for
     * @param results_dir the directory to return the files in to
     * @return PXJob the same PXJob, but with the results variables set.
     * @throws java.lang.Exception thrown if any of the variables specified above
     * aren't validly set
     */
    public abstract PXJob getJobResults(PXJob job, String results_dir) throws Exception;

    
    //THIS METHOD IS NOT YET USED, IT'S HERE FOR FUTURE RELEASES
    
    /**
     * Performs an action on the job.
     * 
     * @param action String the action to perform on the job
     * @param job PXJob the job to perform it on
     * @return Boolean whether the action was performed or not
     * @throws java.lang.Exception thrown if the action is not a valid action
     */
    public abstract Boolean performGridActionOnJob(String action, PXJob job) throws Exception;
    
}
